/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

using System;

namespace Lucene.Net.Index
{
    
    /// <summary> The TermVectorMapper can be used to map Term Vectors into your own
    /// structure instead of the parallel array structure used by
    /// <see cref="Lucene.Net.Index.IndexReader.GetTermFreqVector(int,String)" />.
    /// <p/>
    /// It is up to the implementation to make sure it is thread-safe.
    /// 
    /// 
    /// 
    /// </summary>
    public abstract class TermVectorMapper
    {
        
        private bool ignoringPositions;
        private bool ignoringOffsets;
        
        
        protected internal TermVectorMapper()
        {
        }
        
        /// <summary> </summary>
        /// <param name="ignoringPositions">true if this mapper should tell Lucene to ignore positions even if they are stored
        /// </param>
        /// <param name="ignoringOffsets">similar to ignoringPositions
        /// </param>
        protected internal TermVectorMapper(bool ignoringPositions, bool ignoringOffsets)
        {
            this.ignoringPositions = ignoringPositions;
            this.ignoringOffsets = ignoringOffsets;
        }
        
        /// <summary> Tell the mapper what to expect in regards to field, number of terms, offset and position storage.
        /// This method will be called once before retrieving the vector for a field.
        /// 
        /// This method will be called before <see cref="Map(String,int,TermVectorOffsetInfo[],int[])" />.
        /// </summary>
        /// <param name="field">The field the vector is for
        /// </param>
        /// <param name="numTerms">The number of terms that need to be mapped
        /// </param>
        /// <param name="storeOffsets">true if the mapper should expect offset information
        /// </param>
        /// <param name="storePositions">true if the mapper should expect positions info
        /// </param>
        public abstract void  SetExpectations(System.String field, int numTerms, bool storeOffsets, bool storePositions);
        /// <summary> Map the Term Vector information into your own structure</summary>
        /// <param name="term">The term to add to the vector
        /// </param>
        /// <param name="frequency">The frequency of the term in the document
        /// </param>
        /// <param name="offsets">null if the offset is not specified, otherwise the offset into the field of the term
        /// </param>
        /// <param name="positions">null if the position is not specified, otherwise the position in the field of the term
        /// </param>
        public abstract void  Map(System.String term, int frequency, TermVectorOffsetInfo[] offsets, int[] positions);

        /// <summary> Indicate to Lucene that even if there are positions stored, this mapper is not interested in them and they
        /// can be skipped over.  Derived classes should set this to true if they want to ignore positions.  The default
        /// is false, meaning positions will be loaded if they are stored.
        /// </summary>
        /// <value> false </value>
        public virtual bool IsIgnoringPositions
        {
            get { return ignoringPositions; }
        }

        /// <summary> </summary>
        /// <seealso cref="IsIgnoringPositions()"> Same principal as <see cref="IsIgnoringPositions()" />, but applied to offsets.  false by default.
        /// </seealso>
        /// <value> false </value>
        public virtual bool IsIgnoringOffsets
        {
            get { return ignoringOffsets; }
        }

        /// <summary> Passes down the index of the document whose term vector is currently being mapped,
        /// once for each top level call to a term vector reader.
        /// <p/>
        /// Default implementation IGNORES the document number.  Override if your implementation needs the document number.
        /// <p/> 
        /// NOTE: Document numbers are internal to Lucene and subject to change depending on indexing operations.
        /// 
        /// </summary>
        /// <param name="documentNumber">index of document currently being mapped
        /// </param>
        public virtual void  SetDocumentNumber(int documentNumber)
        {
        }
    }
}